<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) GK Software AG and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
<title>Avoiding resource leaks</title>
</head>
<body>
<h1> Avoiding Resource Leaks </h1>
<p>
Classes implementing the interface <code>java.io.Closeable</code> (since JDK 1.5) and
<code>java.lang.AutoCloseable</code> (since JDK 1.7) are considered to represent external
resources, which should be closed using method <code>close()</code>, when they are 
no longer needed.
</p>
<p>
The Eclipse Java compiler is able to analyze whether code using such types adheres
to this policy. E.g., the following snippet represents an obvious resource leak:
</p>
<pre>    int len(File f) throws IOException {
        InputStream stream = new FileInputStream(f);
        return stream.available();
    }
</pre>
<p>
The compiler will flag this with <b>"Resource leak: 'stream' is never closed".</b>
<h2>Basic Flow Analysis for Resource Leaks</h2>
<p>
Flow analysis detects the following situations:
</p>
<ul>
<li>A resource is definitely not closed</li>
<li>A resource is not closed on all control flows (flagged as "may not be closed")</li>
<li>A resource is not closed at a method exit point (return statement or when an exception is raised) (definitely or on some control flow)</li>
<li>In a Java 7 program a resource is closed but the code could still be improved by using a try-with-resources statement.</li>
</ul>
<p>
Additionally, flow analysis tries to follow resource values through variable assignments.
However, if different resources may be assigned to the same variable (on different control flows or in sequence),
the analysis can become less accurate.
</p>
<p>Not all the analysis is enabled by default. Please consult the <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#resource-leak">compiler preferences</a> 
regarding the individual configuration options.
</p>
<p><strong>Hints:</strong> Code will generally be easier to analyze (and easier to understand by human readers)
if resource-type variables are not reused for different purposes.
Ideally, in Java 7 programs all resources should be managed with a try-with-resources statement.
</p>
<h2>Ownership / Responsibility</h2>
<p>
The above diagnostics basically assume that a method that creates an instance of a resource type
is also responsible for closing this resource.
However, some resources will be shared among several methods. Here the analysis makes the following assumptions:
</p>
<ul>
<li>If a method returns a resource to its caller, it is not responsible for closing; no problem is reported.</li>
<li>If a resource is stored in a field, no single method is considered as responsible for closing; no problem is reported.</li>
<li>If a method obtains a resource via a method call rather than by a <code>new</code> expression, it may or may not
 be responsible; any problems are only flagged as potential resource leaks.</li>
<li>If a resource is passed as an argument in a method call or constructor call, the current method
may or may not be responsible; any problems are only flagged as potential resource leaks.</li>
</ul>
<h2>Resource Wrappers and Resource-free Closeables</h2>
<p>
The JDK defines a few classes which implement <code>Closeable</code> but do not directly represent
a resource at the level of the operating system.
</p>
<p><code>java.io.StringReader</code> is an example of a closeable that doesn't require calling <code>close()</code>
because <b>no operating system resources</b> are held that would require clean-up.
The analysis uses an explicit white list to detect classes from <code>java.io</code> that fall in this category.
No resource leak warnings are issued regarding these classes.
</p>
<p>Instances of classes like <code>java.io.BufferedInputStream</code> are <b>wrappers</b> around another resource
(where wrappers can be applied at multiple levels).
Also these objects do not directly represent an operating system resource.
If the wrapped resource is closed, the wrapper doesn't need closing.
Conversely, if a wrapper is closed this will include closing of the wrapped resource.
The analysis has a second white list for detecting wrapper resources, and will recognize whether
the underlying actual resource will be closed directly or indirectly via the wrapper.
Either one suffices to silence warnings regarding resource leaks.
The white list contains classes from <code>java.io</code>, <code>java.util.zip</code>, <code>java.security</code>, <code>java.beans</code>
and <code>java.sound.sampled</code>.
</p>
<p><strong>Hint:</strong> It is generally preferable/safest to close the outermost wrapper, not a wrapped resource.
</body>
</html>
